/************************************************************************
This file is part of lpc2xxx package for the simpleRTJ virtual machine.

This file is covered by the GNU GPL with the following exception:
  As a special exception, the copyright holders of this library give you permission
  to link this library with independent modules to produce an executable, regardless
  of the license terms of these independent modules, and to copy and distribute the
  resulting executable under terms of your choice, provided that you also meet, for
  each linked independent module, the terms and conditions of the license of that
  module. An independent module is a module which is not derived from or based on
  this library. If you modify this library, you may extend this exception to your
  version of the library, but you are not obligated to do so. If you do not wish
  to do so, delete this exception statement from your version.


THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY,  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL RTJ COMPUTING BE LIABLE FOR ANY CLAIM, DAMAGES
OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.

Copyright (c) 2000-2006 RTJ Computing Pty. Ltd. All rights reserved.
***********************************************************************/
package lpc2xxx.comm;



/**
 * Class providing access to SPI (Serial Peripheral Interface) on the LPC21xx.<br>
 * Add your own code to implement additional features if required.
 */
public class SPI
{
    /** SPI write command */
    private final static int WRITE  = 0;
    /** SPI read command */
    private final static int READ   = 1;

    /**
     * Hidden constructor - can't be instantiated. Accessed only via provided
     * static methods.
     */
    private SPI()
    {
    }

    /**
     * Initialises the SPI.
     * @param csPin one of the hw.GPIO.Pxx values identifying the pin that will be
     *              used to activate the chip select signal of slave device.
     * 
     */
    public static native void init(int csPin);

    /**
     * Sends values of byte array to slave SPI device.<br>
     * Method is non-blockin, use <code>ready()</code> method to check if SPI is
     * ready for the next command.
     * @param src byte array containing data for sending to SPI device.
     */
    public static void write(byte[] src)
    {
        command(WRITE, src, 0, src.length);
    }

    /**
     * Sends the content of String to slave SPI device.<br>
     * Method is non-blockin, use <code>ready()</code> method to check if SPI is
     * ready for the next command.
     * @param val String containing data for sending to SPI device.
     */
    public static synchronized void write(String val)
    {
        byte[] b = val.getBytes();
        command(WRITE, b, 0, b.length);
    }

    /**
     * Sends values of byte array to slave SPI device.<br>
     * Method is non-blockin, use <code>ready()</code> method to check if SPI is
     * ready for the next command.
     * @param src byte array containing data for sending to SPI device.
     * @param offs starting offset into the byte array
     * @param len number of bytes to send
     */
    public static void write(byte[] src, int offs, int len)
    {
        command(WRITE, src, offs, len);
    }

    /**
     * Reads data from the slave SPI device.<br>
     * Method is non-blockin, use <code>ready()</code> method to check if SPI is
     * ready for the next command.
     * @param len number of bytes to read
     * @return byte array containing the received bytes
     */
    public static synchronized byte[] read(int len)
    {
        byte[] b = new byte[len];
        command(READ, b, 0, len);
        return b;
    }

    /**
     * Reads data from the slave SPI device.<br>
     * Method is non-blockin, use <code>ready()</code> method to check if SPI is
     * ready for the next command.
     * @param len number of bytes to read
     * @return String containing the received bytes
     */
    public static synchronized String readStr(int len)
    {
        byte[] b = new byte[len];
        command(READ, b, 0, len);
        return new String(b, 0, len);
    }

    /**
     * Reads data from the slave SPI device.<br>
     * Method is non-blockin, use <code>ready()</code> method to check if SPI is
     * ready for the next command.
     * @param len number of bytes to read
     * @return byte array containing the received bytes
     */
    public static void read(byte[] dest, int offs, int len)
    {
        command(READ, dest, offs, len);
    }

    /**
     * Waits for SPI to become ready to accept new commands.<br>
     * Method is blocking and will return once the SPI is ready for the next command.
     */
    public static synchronized void waitReady()
    {
        while (!ready())
            Thread.yield();
    }

    /**
     * Read/Write command for transferring data from/to slave SPI device.<br>
     * @param cmd READ/WRITE command identifier
     * @param arr source/destination byte array 
     * @param offs offset to byte array
     * @param len number of bytes to transfer
     */
    private static native void command(int cmd, byte[] arr, int offs, int len);

    /**
     * Checks if the SPI is ready to accept a new command.
     * @return true if SPI ready for a new command
     */
    public static native boolean ready();
}
